TTTTccccllll____AAAAssssyyyynnnnccccCCCCrrrreeeeaaaatttteeee creates an asynchronous handler and returns a token for
it. The asynchronous handler must be created before any occurrences of
the asynchronous event that it is intended to handle (it is not safe to
create a handler at the time of an event). When an asynchronous event
occurs the code that detects the event (such as a signal handler) should
call TTTTccccllll____AAAAssssyyyynnnnccccMMMMaaaarrrrkkkk with the token for the handler. TTTTccccllll____AAAAssssyyyynnnnccccMMMMaaaarrrrkkkk will
mark the handler as ready to execute, but it will not invoke the handler
immediately. Tcl will call the _p_r_o_c associated with the handler later,
when the world is in a safe state, and _p_r_o_c can then carry out the
actions associated with the asynchronous event. _P_r_o_c should have
arguments and result that match the type TTTTccccllll____AAAAssssyyyynnnnccccPPPPrrrroooocccc:
typedef int Tcl_AsyncProc(
ClientData _c_l_i_e_n_t_D_a_t_a,
Tcl_Interp *_i_n_t_e_r_p,
int _c_o_d_e);
The _c_l_i_e_n_t_D_a_t_a will be the same as the _c_l_i_e_n_t_D_a_t_a argument passed to
TTTTccccllll____AAAAssssyyyynnnnccccCCCCrrrreeeeaaaatttteeee when the handler was created. If _p_r_o_c is invoked just
after a command has completed execution in an interpreter, then _i_n_t_e_r_p
will identify the interpreter in which the command was evaluated and _c_o_d_e
will be the completion code returned by that command. The command's
result will be present in _i_n_t_e_r_p->_r_e_s_u_l_t. When _p_r_o_c returns, whatever it
leaves in _i_n_t_e_r_p->_r_e_s_u_l_t will be returned as the result of the command
and the integer value returned by _p_r_o_c will be used as the new completion
code for the command.
It is also possible for _p_r_o_c to be invoked when no interpreter is active.
This can happen, for example, if an asynchronous event occurs while the
application is waiting for interactive input or an X event. In this case
_i_n_t_e_r_p will be NULL and _c_o_d_e will be 0, and the return value from _p_r_o_c
will be ignored.
The procedure TTTTccccllll____AAAAssssyyyynnnnccccIIIInnnnvvvvooookkkkeeee is called to invoke all of the handlers
that are ready. The global variable ttttccccllll____AAAAssssyyyynnnnccccRRRReeeeaaaaddddyyyy will be non-zero
whenever any asynchronous handlers are ready; it can be checked to avoid
calls to TTTTccccllll____AAAAssssyyyynnnnccccIIIInnnnvvvvooookkkkeeee when there are no ready handlers. Tcl checks
ttttccccllll____AAAAssssyyyynnnnccccRRRReeeeaaaaddddyyyy after each command is evaluated and calls TTTTccccllll____AAAAssssyyyynnnnccccIIIInnnnvvvvooookkkkeeee
if needed. Applications may also call TTTTccccllll____AAAAssssyyyynnnnccccIIIInnnnvvvvooookkkkeeee at interesting
times for that application. For example, Tk's event handler checks
ttttccccllll____AAAAssssyyyynnnnccccRRRReeeeaaaaddddyyyy after each event and calls TTTTccccllll____AAAAssssyyyynnnnccccIIIInnnnvvvvooookkkkeeee if needed. The
_i_n_t_e_r_p and _c_o_d_e arguments to TTTTccccllll____AAAAssssyyyynnnnccccIIIInnnnvvvvooookkkkeeee have the same meaning as for
_p_r_o_c: they identify the active interpreter, if any, and the completion
code from the command that just completed.
TTTTccccllll____AAAAssssyyyynnnnccccDDDDeeeelllleeeetttteeee removes an asynchronous handler so that its _p_r_o_c will
never be invoked again. A handler can be deleted even when ready, and it
will still not be invoked.
If multiple handlers become active at the same time, the handlers are
invoked in the order they were created (oldest handler first). The _c_o_d_e
and _i_n_t_e_r_p->_r_e_s_u_l_t for later handlers reflect the values returned by
earlier handlers, so that the most recently created handler has last say
about the interpreter's result and completion code. If new handlers
